`co(4,7);──────────────────────────── /// Creating dialogs ────────────────────────────`co();

 ┌──────────────────────────────────────────────────────────────────────────┐
 │                          `keyword(Introduction,/// Introduction);                                    │
 │                          `keyword(TUI Params,/// TUI Params);                                      │
 │                          `keyword(The Toolbox,/// The Toolbox);                                     │
 │                          `keyword(Modifying the Dialog,/// Modifying the Dialog);                            │
 │                          `keyword(Sizing/Moving the dialog,/// Sizing/Moving the dialog);                        │
 │                          `keyword(1) Adding Text,/// Adding Text);                                  │
 │                          `keyword(2) Adding a Box,/// Adding a Box);                                 │
 │                          `keyword(3) Adding a Button,/// Adding a Button);                              │
 │                          `keyword(4) Adding a Check Box,/// Adding a Check Box);                           │
 │                          `keyword(5) Adding an Icon,/// Adding an Icon);                               │
 │                          `keyword(6) Adding a Slider,/// Adding a Slider);                              │
 │                          `keyword(7) Adding Data Entry Fields,/// Adding Data Entry Fields);                     │
 └──────────────────────────────────────────────────────────────────────────┘

`co(15,?);/// Introduction`co();
	  In this section, we will create a dialog step by step, describing each
	object and its associated parameters.  This is quite a bit to absorb all
	at once, but it's really quite simple since many objects have so much in
	common.  Be sure to run the tutorials provided; there is no better way to
	learn how to use the TUICP than watching a recorded session.

	  To create a dialog, we first must start with a new TUI.  Do this by
	selecting "New TUI" in the "Files" menu.  Now select "Add Dialog" from the
	"Dialogs" menu.  We can edit the global TUI parameters if desired by
	choosing the "TUI parameters" under the "Files" menu.

`co(15,?);/// TUI Params`co();
	  This dialog gives you global control over all dialogs within the current
	TUI.  First we can set the screen rows to 25 or 43/50 (EGA/VGA), and the
	default desktop color.  We can also choose whether to use the UltraWin
	Window Manager.  If you wish to use this elsewhere in your program select
	this item.  Using the Window Manager is recommended as it simplifies
	adding/deleting windows and takes care of all the masking, etc.
  
	  When you know your programs will be running on EGA/VGA systems you also
	have control over the video palette.  Clicking on default will reload the
	standard EGA/VGA palette values.  Clicking on custom will pull up a
	palette dialog which allows you to edit each of 16 palette values.  Simply
	click on the desired register, which is represented by one of sixteen
	small boxes at the top of the dialog, and adjust the individual Red,
	Green, and Blue components using the three sliders.  Notice the screen
	change as you adjust the values!

	  For EGA/VGA systems, you can also select alternate custom fonts.  Two
	font sets can be loaded at once, with the second set activated by using
	the high eight background colors.  To load a different font, simply click
	on the desired set and select the font file you want.  Be prepared, your
	screen will change immediately to the new font.  Loading a special font
	that contains characters other than the standard text into font set one
	will make the TUICP and your dialogs unreadable.  If you need custom icon
	fonts, always load them into the second set.  A number of fonts are
	included with InTUItion, including fat and thin 8x14 and a font containing
	common icons.
 
	  We can also set extended colors on EGA/VGA systems.  This allows you to
	use all 16 foreground, and all 16 background colors for a total of 256
	combinations, without the high background colors blinking.  When using two
	font sets, you will typically want extended colors on.  If the default is
	selected, the upper eight background colors will blink.
  
	  That's it for the TUI parameters.  Now click on OK and move your mouse
	to the new dialog and press the right button.  A default dialog will
	appear. We can edit the parameters of this new dialog by clicking the
	right button while the mouse is over the dialog. But first let's learn how
	to use the toolbox.

`co(15,?);/// The Toolbox`co();
	  The TUICP toolbox is a user customizable dialog that holds the various
	objects.  It is quite simply a TUI with only one dialog.  As such you may
	load it into the TUICP and put in your favorite object variations. You may
	even elect to have different toolboxes depending on your current project.

	  The toolbox is activated by pressing the left mouse button when the
	mouse is outside of the dialog.  Objects are "picked" off of the toolbox
	by moving to them and pressing and holding the left button.  The toolbox
	will disappear and you can then move the object to the desired location.
	If any portion of the object is outside of the dialog it will be
	discarded.  All objects can be moved and sized by grabbing the top row or
	lower-right corner and "dragging" them into place.  To remove an object,
	simply grab it and drag it off of the dialog.

	  All objects that will be accessed from your program must be named.  This
	name will be used in your programs to identify the object.  Move the mouse
	to the name field and press the left button.  Now enter the desired name.
	As you type, InTUItion converts your characters to upper case.  This
	should prevent any clashes with function or variable names you may create.

	  All objects have various colors associated with them.  To edit an
	object's color, click on the desired button.  A color dialog box will
	appear.  Move your mouse to the desired color and click the left button.
	You may also use the keypad arrow keys to select a new color.  You can
	click on "Cancel" if you wish to leave the color unchanged.

`co(15,?);/// Modifying the Dialog`co();
	  First, click the right button on the main dialog box, then name the
	dialog and set its colors as described above.  Now all that's left is
	choosing the border style.  One of four styles are available; None,
	Single, Double, or Solid; choose your favorite.  That's all there is to
	editing the dialog itself.  Let's move on to sizing the dialog.

`co(15,?);/// Sizing/Moving the dialog`co();
	  To size the dialog, simply "grab" the lower right hand corner by moving
	your mouse to it and pressing and holding down the left button.  Now
	"drag" the dialog to the proper size.  When finished, release the button.
	To move the dialog, we do a similar operation by "grabbing" the top row
	and "dragging" the entire dialog to the desired position.  This is the
	position the dialog will appear on the users screen unless the TUI
	variables are altered by your program by calling position_dialog or
	center_dialog.  So much for this, it's really pretty inTUItive, isn't it?

`co(15,?);/// Adding Text`co();
	  Text objects are used primarily for labeling other objects within the
	dialog and do not perform any action.  To add a text object, "grab" it off
	of the toolbox and place it in the desired spot.  While the mouse is still
	over the text object, click the right mouse button.  The text dialog will
	appear.  Move the mouse cursor to the text string, click the left button,
	and enter the desired text.  This is the text that will be displayed
	within the text object.  If the object is larger than the text, the text
	will be centered, both vertically and horizontally.  Now set the color for
	the text.  The last remaining item is to set the style to "normal" or
	"shadowed". A shadowed object always has a black shadow to the lower
	right, giving the object a 3D look at the expense of an additional line
	and column.

`co(15,?);/// Adding a Box`co();
	  Boxes are used to organize the dialog into distinct areas and to control
	radio buttons.  (See Radio buttons for more details). To add a box object,
	"grab" it off of the toolbox and place it in the desired spot.  While the
	mouse is still over the box object, click the right mouse button.  The box
	dialog will appear.  Name the object, and set its color and style.

	  Ok, now we run into a few new parameters.  Since a box can return
	control when activated, we can define its hot key.  When the user presses
	this key or clicks on the object, the action associated with the item will
	occur. To define the hot key, click on the hot key button and press the
	desired hot key on your keyboard.  Alt keys are quite common and
	recommended.  Keep in mind that the same hot key can be used for each
	dialog as the hot key is only associated with the current dialog.

	  The final parameter is "Exit On".  The box can return control in one of
	three ways, or anytime the hot key is pressed.
	1) Exit on press   - when the mouse is over the object and a button is
											 pressed.
	2) Exit on release - when the mouse is over the object and a button is
											 released.
	3) Exit on over    - anytime the mouse is over the object.         

		Exit on press and release are the most commonly used.  Exit on over is
	used where an action must be performed as the user moves his mouse over
	the object.  An example of when you might use this is when you wish to
	"paint" in the dialog box without the user holding down the mouse button.

`co(15,?);/// Adding a Button`co();
	  Buttons are one of the most commonly used objects.  They are the visual
	equivalent of yesteryear's function keys.  To add a button, grab it off of
	the toolbox and place it in the desired spot.  While the mouse is still
	over the button object, click the right mouse button.  The button dialog
	will appear.  Name the object and choose the button style.

	  Buttons, like boxes, have a hot key and exit parameters.  They also have
	displayed text like text objects.  Click on the text string and type in
	the desired text.  Additional color control is needed for buttons.  First,
	we set the normal color.  We also have a color associated with the first
	character.  This can be the same as the normal color but is often
	different and commonly associated with the hot key.  The first letter is
	not necessarily the first character in the string, it is the character at
	the position set by "First Index".  An example may help.  Let's say we
	have a button with the text "Cancel".  We first set the hot key to Alt-C.
	Now we set the normal color to lightgray on blue.  To signal the user that
	Alt-C is the hot key, we highlight the C in "Cancel" by setting the first
	position to zero, and the first letter color to yellow on blue. In
	addition to the normal colors, we have a different set of colors when the
	object is selected.  If different from the normal colors, the item will
	change colors when selected.  Furthermore, the user can tab to the button
	but not actually select it.  A third color is used here.  Note that the
	only the text color of the tab attribute is used when the user tabs to the
	button. This allows the user to see if the button is on or off even when
	the tab resides on the button.

	  Buttons can be normal, radio, or deselectable radio.  Normal buttons are
	the simplest and have no effect on any other objects.  Radio buttons give
	the user one and only one choice.  For instance, the user may have to
	select a disk drive; A, B, C, or D.  One and only one choice must be made.
	A choice of no drive is not allowed.  A deselectable radio button is
	similar but allows a no choice condition to occur.  This might be used to
	choose a second disk drive, which may not exist.

	  Radio buttons must be grouped in order to work properly.  By default,
	all buttons have the dialog as their parent.  When this is the case, when
	any radio button is selected, all others turn off.  In some cases,
	multiple sets of independent radio buttons are needed in one dialog.  We
	accomplish this by grouping associated buttons within a box.  Simply
	create a box large enough to hold all associated buttons and move the
	buttons inside of the box.  The box becomes the "parent" and the buttons
	the "children".  Now when the box is moved, all buttons within it move. If
	you don't want the box to be visible, simply set its color to the same as
	the background dialog.  Since the box is unlikely to be used on its own,
	you do not need to name it.  Now when you click on a button within this
	box, all other buttons within the box will be turned off, but all other
	buttons in the dialog will be unaffected.

`co(15,?);/// Adding a Check Box`co();
	  Check boxes are virtually the same as buttons.  The only differences are
	the displayed text and the check mark itself.  The check mark serves as a
	replacement to the selected color.  To set the check mark, click on the
	Mark button and choose the desired character.  Set the check position as
	well.  This is the offset within the displayed string of the check mark.
	Though it is not required, it is a good idea to be consistent with check
	boxes.  For instance, all radio check boxes in InTUItion use ( ) while
	normal check boxes use [ ].  You can put any text before and after the
	check mark, including spaces, allowing a wide variety of styles to be
	used. A check box without a check mark is simply a button!

`co(15,?);/// Adding an Icon`co();
	  Icons are basically buttons that can contain two-dimensional images of
	any size created with the TUICP's built-in icon editor. (Similar to the
	font editor included in InTUItion).  The image can contain any characters,
	including your own fonts.  Since you can edit your own fonts you can truly
	create two-color graphics icons in mosaic fashion.  A good example might
	be a file selector.  Instead of just displaying drive A,B,C,D etc., you
	can create an icon for a 5 1/4"  & 3 1/2" floppy, a hard disk, and perhaps
	a ram disk. By adding these icons to your dialog, your text based
	application has graphics as well!  Add an icon to your dialog like you
	would any other object and click on the right button to display the
	icon's edit dialog.

	  Icons have the same parameters as buttons except that instead of
	displaying text, they display one of two images.  Image one is the normal
	image displayed and image two is displayed when the icon is selected.  To
	create the image, click on the image button and the image dialog will
	appear.  Several buttons are available here:                              

	Image #1 - selects the normal image.
	Image #2 - selects the image that is displayed when the icon is selected.
	Paint:   - selects a new paint character.
	Clear    - clears the image.
	Copy     - copies the displayed image to the image not displayed.
	Cancel   - ignores the changes and returns to the previous dialog.
	Ok       - accepts the changes and returns to the previous dialog.

	  If the image is larger than the dialog box, you can scroll the image
	both horizontally and vertically.  If smaller, the editor restricts
	painting to an area equal to the size of the image within your dialog.

	  To paint, select a character by clicking on the paint button.  Now
	simply move your mouse to the desired character and click the left button.
	This character will now be displayed anytime you click the left button
	while in the icon editor box.  You can also hold down the button and
	"draw" with it to speed up the editing process.  Clicking the left button
	will set the cell to the paint character, while clicking the right button
	will clear the cell.

	  Since an icon can be as large as the entire dialog, you can be very
	creative here, using custom fonts and colors, to give you text programs a
	unique flair and detail rarely seen in text-mode-only programs.

`co(15,?);/// Adding a Slider`co();
	  Sliders are used when more data is available than the limited dialog
	size can display.  An editor or file browser is a good example.  Both
	horizontal and vertical sliders can be used. To add a slider, grab it off
	of the toolbox and place it at the desired location.  You can size and
	move the slider anywhere within the dialog.  Note that the slider can only
	be one character tall or wide, depending on whether it's horizontal or
	vertical. When the bounding box is wider than tall, the slider becomes a
	horizontal slider, otherwise it becomes vertical.  No other settings are
	needed. While the mouse is still over the slider object, click the right
	mouse button. The slider dialog will appear. Name the object and choose
	the style.

	  The slider object has three colors that can be selected; the arrow,
	track, and grab box.  Simply click on the desired one and edit its color.
	There are six characters used to draw a slider that can be customized.
	The right and left arrows for a horizontal slider, the up and down arrows
	for a vertical slider, the slider track or body, and the grab box, which
	indicates the current position.  To change these characters, simply click
	on the desired item and choose a character. 

	  Sliders can be `co(15,?);Selectable`co();, where they allow the user to control
	and move the slider position by moving the grab box.  If `co(15,?);Selectable`co(); is
	off, then the slider is strictly a visual indicator controlled by the
	program, and the user cannot move the grab box.

  	`co(15,?);Exit on use`co(); returns control to the program so that you can take
	action anytime the user adjusts the slider.  If this flag is not set, then
	the program should simply read the slider value when needed.  The slider
	object will keep track of the value, adjusting it automatically for you.
	See the InTUItion function library reference for more details.

  	The slider can be adjusted by the user in one of three ways.  First,
	clicking on the arrows will increment/decrement the slider position by
	one. Second, clicking within the slider track will increment/decrement the
	slider position by the page amount set by your program.  Last, the slider
	can be adjusted by grabbing the grab box and moving it to the desired
	position.  The slider position will be set relative to the grab box
	location.

`co(15,?);/// Adding Data Entry Fields`co();
	  Data entry fields are perhaps the most complex yet useful objects.  They
	provide a method for the user to input information into your program.
	Let's start by adding a text field to our dialog and clicking the right
	button to display the input parameters.

	  Many parameters for data entry are the same as with other objects.
	However, there are several additional parameters.  First, we have the
	text, mask, and template parameter strings.  Those of you familiar with
	the UltraWin functions wn_gets and wn_gets_ll will feel right at home
	here. Those of you who are not may want to review these function
	descriptions in the UltraWin function library documentation.  We will show
	several examples here for clarity.  Let's say we need the user to type in
	a date field.  Set the fields as follows.

`co(15,?);      Text: ""
      Mask: "__/__/__"
  Template: "## ## ##"`co();

	  The '#' in the template tells the input routines to only accept digits.
	The spaces in the template tell the input routines to skip over this area
	as the user types.  The mask is "overlayed" onto the screen and gives the
	user an idea of the data form.  The text field content is not important,
	as InTUItion will fill it out for you according to what the user types.
	It typically will start off as a zero-length null-terminated string,
	though you may want to set it to a default string to make it easier on the
	user.

	  Now when a user enters a date, only digits will be accepted and the /
	will automatically be skipped so that the user can simply enter 010192.
	Furthermore, if it is desired that additional field validation occur as
	the user types, the UltraWin wn_gets_ll function has a "hook" that will
	call your own validation routine for every character entered.  See the
	UltraWin documentation and the STR_DEMO.C source code for more details.

	  Entry fields can be `co(15,?);tabable`co();, allowing the user to tab to the
	field and press <Enter> to begin input (<Enter> is not required if the
	do_dialog function is called with the DO_INPUT_ADV define).  In addition
	to the TAB key, the keypad arrow keys will cycle forward and backward
	through the tabbed items.  If the item is not set as `co(15,?);tabable`co();, then the
	user must click the mouse on the entry to select it for input.

	  The `co(15,?);Capitalize`co(); flag can also be selected.  This flag causes
	the first letter of each word to be capitialized as the user types, and is
	useful in an entry field such as a name or title.

  	The `co(15,?);Type R-to-L`co(); flag causes input to occur right-to-left, rather
	than the usual left-to-right.  This flag is very useful for data entry
	form dialogs that contain price fields.  Please note that when this flag
	is selected that the cursor starts at the right side of the input, and the
	characters are "scooted" over to the left for each valid character
	entered.

	  The `co(15,?);<CR> on Full`co(); flag is especially useful for fixed-length
	fields. This flag causes the same effect as the user hitting a <CR> when
	the last character of the field is typed, thus eliminating an extra
	keypress.  This feature is particularly useful on a long list of fields of
	the same type. If the flag is off, then the user must press <CR> to accept
	each entry.

	  The `co(15,?);Clr on Key`co(); flag causes the field to clear when the first
	valid key is pressed.  This is useful when the field contains data the
	user needs to replace.  It is equivalent to the user first pressing CTRL-Y
	and then pressing a valid key.  Like "<CR> on FULL" it saves an extra
	keystroke when set.  If the user first cursors to another part of the
	field the clear is not performed.

  	`co(15,?);Exit on Use`co(); will return control to your program when the user
 	is finished entering data; otherwise, your program can read the string
	value when needed.  "Exit on Use" would be set when the user enters a
	field that immediately requires action by the program.  There are times
	when you might not want it to exit, as when entering a form where you
	don't need the information until all fields are entered and the accept
	button is pressed.

		The strip mask flags, `co(15,?);Strip All`co(); and `co(15,?);Strip End`co(); allow control
	over the input string before it is handed back to your program.  If
	neither flag is set, the entire string is handed back. `co(15,?);If Strip All`co(); is
	set, all mask characters are removed, and if `co(15,?);Strip End`co(); is set, only
	the end mask characters are removed.  Here are a few examples of what
	these mean for input in both left-to-right and right-to-left directions.

	`co(15,?);Left-to-Right (normal) Entry`co();
	--------------------------------------------------------------------------
	No Strip:  entry: "UltraWin Library___"     return: "UltraWin Library___"
  	         entry: "08/09/__"                return: "08/09/__"

	Strip All: entry: "UltraWin Library___"	    return: "UltraWin Library"
						 entry: "08/09/__"                return: "0809"

	Strip End: entry: "UltraWin Library___"	    return: "UltraWin Library"
  	         entry: "08/09/__"                return: "08/09"

	`co(15,?);Right-to-Left (reverse) Entry`co();
	--------------------------------------------------------------------------
	No Strip:  entry: "___UltraWin Library"     return: "___UltraWin Library"
	           entry: "__/08/09"                return: "__/08/09"

	Strip All: entry: "___UltraWin Library"     return: "UltraWin Library"
	           entry: "__/08/09"                return: "0809"
	           entry: "$__99.95"                return: "9995"

	Strip End: entry: "___UltraWin Library"     return: "UltraWin Library"
	           entry: "__/08/09"                return: "08/09"
	           entry: "$__99.95"                return: "99.95"

	  Please note that `co(15,?);Strip All`co(); gives the same returned string regardless
	of input direction, while `co(15,?);Strip End`co(); will strip the mask from the right
	end of the string for right-to-left, and from the left end of the string
	for left-to-right (the end always being away from the initial cursor
	location for both cases).

	  Data entry fields have even more control.  Click on the `co(15,?);Special`co();
	button to pull up an additional control dialog. First we set the length of
	input. The input length can be up to 255 characters, even if the display
	field is less.  The input field will scroll as the user types, displaying
	arrows at the start and end of the field to show the user that additional
	data exists before and after the displayed field.  This allows you to
	gather large strings in a small display area.  A full DOS path name is a
	good example. You can specify a length of 12, which will handle any DOS
	file name in the current path, but when the user needs to enter a full
	length path the field will automatically scroll and accept the input.

	  The validation characters provide a first level of input checking.
	Clicking on one of these will automatically create the mask and template
	so be sure you want to do this before selecting one of these fields.  Here
	is a description of the action each validation character performs:

	All       `co(15,?);*`co(); -  Accepts any character.
	Alpha     `co(15,?);a`co(); -  Accepts only alpha characters a-z, A-Z.
	Alnum     `co(15,?);A`co(); -  Accepts any alpha or numeric character a-z 0-9.
	Upper     `co(15,?);u`co(); -  Accepts only uppercase characters, A-Z.
	Lower     `co(15,?);l`co(); -  Accepts only lowercase characters, a-z.
	To Upper  `co(15,?);U`co(); -  Accepts alpha characters and converts to uppercase a-z, A-Z.
	To Lower  `co(15,?);L`co(); -  Accepts alpha characters and converts to lowercase a-z, A-Z.
	Digits    `co(15,?);#`co(); -  Accepts only the digits 0-9.
	Digits+   `co(15,?);9`co(); -  Accepts digits 0-9, '+', '-', '.', 'E', 'e'.

	  These validation characters can be used in any combination.  Clicking on
	one of these fills the entire template and mask, which can then be edited
	as desired.  For instance, when entering a last name you might want a
	template like "Uaaaaaaaaaa" which converts the first character to
	uppercase and only accepts alpha characters.

	  Several standard types are included in the dialog for easy use.  They
	are as follows:

	Date  -  template = "## ## ##"         mask = "__/__/__"
	Time  -  template = "## ##"            mask = "__:__"
	Phone -  template = " ### ### ####"    mask = "(___)___-____"
	SSN   -  template = "### ## ####"      mask = "___-__-____"
	Money -  template = "#####.##"         mask = "_____.__"

	  Simply choose one and the mask and template will be automatically filled
	out for you.  In addition the "Money" selection will use the length shown
	at the top of the dialog for the total length of the mask and template.
